<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Instrumentation Utilities</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__drutil.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">Instrumentation Utilities</div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gae2b7cca016411251a1dbebc5dbefa4f1"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drutil.html#gae2b7cca016411251a1dbebc5dbefa4f1">drutil_init</a> (void)</td></tr>
<tr class="memitem:gaa18c356df47853e7f0258feced9dd885"><td class="memItemLeft" align="right" valign="top">DR_EXPORT void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drutil.html#gaa18c356df47853e7f0258feced9dd885">drutil_exit</a> (void)</td></tr>
<tr class="memitem:ga2f53127090ac749d0c17713f0eb25571"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drutil.html#ga2f53127090ac749d0c17713f0eb25571">drutil_insert_get_mem_addr</a> (void *drcontext, instrlist_t *bb, <a class="el" href="structinstr__t.html">instr_t</a> *where, <a class="el" href="structopnd__t.html">opnd_t</a> memref, reg_id_t dst, reg_id_t scratch)</td></tr>
<tr class="memitem:ga7e3d7896921f5bc20dd70d0de666ce6f"><td class="memItemLeft" align="right" valign="top">DR_EXPORT uint&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drutil.html#ga7e3d7896921f5bc20dd70d0de666ce6f">drutil_opnd_mem_size_in_bytes</a> (<a class="el" href="structopnd__t.html">opnd_t</a> memref, <a class="el" href="structinstr__t.html">instr_t</a> *inst)</td></tr>
<tr class="memitem:gae38961d42fc285d7f9034c4b02690cae"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drutil.html#gae38961d42fc285d7f9034c4b02690cae">drutil_expand_rep_string</a> (void *drcontext, instrlist_t *bb)</td></tr>
<tr class="memitem:gab75e6f41cd4ee5afaec592725abe1557"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drutil.html#gab75e6f41cd4ee5afaec592725abe1557">drutil_expand_rep_string_ex</a> (void *drcontext, instrlist_t *bb, OUT bool *expanded, OUT <a class="el" href="structinstr__t.html">instr_t</a> **stringop)</td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="gaa18c356df47853e7f0258feced9dd885"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT void drutil_exit </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Cleans up the drutil extension. </p>

</div>
</div>
<a class="anchor" id="gae38961d42fc285d7f9034c4b02690cae"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drutil_expand_rep_string </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>drcontext</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">instrlist_t *&#160;</td>
          <td class="paramname"><em>bb</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Expands single-instruction string loops (those using the <code>rep</code> or <code>repne</code> prefixes) into regular loops to simplify memory usage analysis. This is accomplished by arranging for each single-instruction string loop to occupy a basic block by itself (by truncating the prior block before the loop, and truncating instructions after the loop) and then exanding it into a multi-instruction loop.</p>
<p>WARNING: The added multi-instruction loop contains several control-transfer instructions and is not straight-line code, which can complicate subsequent analysis routines.</p>
<p>WARNING: The added instructions have translations that are in the middle of the original string loop instruction. This is to prevent passes that match exact addresses from having multiple hits and doing something like inserting 6 clean calls.</p>
<p>WARNING: The added instructions include a jecxz instruction which will not be transformed into a 32-bit-reach instruction: thus, excessive added instrumentation may result in a reachability problem.</p>
<p>The client must use the <code>drmgr</code> Extension to order its instrumentation in order to use this function. This function must be called from the application-to-application ("app2app") stage (see <a class="el" href="group__drmgr.html#gae270eeb1ab24d4e05f8588b23822f45c">drmgr_register_bb_app2app_event()</a>).</p>
<p>This transformation is deterministic, so the caller can return DR_EMIT_DEFAULT from its event.</p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="gab75e6f41cd4ee5afaec592725abe1557"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drutil_expand_rep_string_ex </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>drcontext</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">instrlist_t *&#160;</td>
          <td class="paramname"><em>bb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">OUT bool *&#160;</td>
          <td class="paramname"><em>expanded</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">OUT <a class="el" href="structinstr__t.html">instr_t</a> **&#160;</td>
          <td class="paramname"><em>stringop</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Identical to <a class="el" href="group__drutil.html#gae38961d42fc285d7f9034c4b02690cae">drutil_expand_rep_string()</a> but returns additional information.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">drcontext</td><td>The opaque context </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">bb</td><td>Instruction list passed to the app2app event </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">expanded</td><td>Whether any expansion occurred </td></tr>
    <tr><td class="paramdir">[out]</td><td class="paramname">stringop</td><td>The string instruction in the expanded loop</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="gae2b7cca016411251a1dbebc5dbefa4f1"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drutil_init </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Initializes the drutil extension. Must be called prior to any of the other routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to <a class="el" href="group__drutil.html#gaa18c356df47853e7f0258feced9dd885">drutil_exit()</a>.</p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga2f53127090ac749d0c17713f0eb25571"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drutil_insert_get_mem_addr </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>drcontext</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">instrlist_t *&#160;</td>
          <td class="paramname"><em>bb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="structinstr__t.html">instr_t</a> *&#160;</td>
          <td class="paramname"><em>where</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="structopnd__t.html">opnd_t</a>&#160;</td>
          <td class="paramname"><em>memref</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">reg_id_t&#160;</td>
          <td class="paramname"><em>dst</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">reg_id_t&#160;</td>
          <td class="paramname"><em>scratch</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Inserts instructions prior to <code>where</code> in <code>bb</code> that determine and store the memory address referred to by <code>memref</code> into the register <code>dst</code>. May clobber the register <code>scratch</code>. Supports far memory references. For far memory references via DS and ES, we assume that the segment base is 0.</p>
<p>To obtain each memory address referenced in a single-instruction string loop, use <a class="el" href="group__drutil.html#gae38961d42fc285d7f9034c4b02690cae">drutil_expand_rep_string()</a> to transform such loops into regular loops containing (non-loop) string instructions.</p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga7e3d7896921f5bc20dd70d0de666ce6f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT uint drutil_opnd_mem_size_in_bytes </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="structopnd__t.html">opnd_t</a>&#160;</td>
          <td class="paramname"><em>memref</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="structinstr__t.html">instr_t</a> *&#160;</td>
          <td class="paramname"><em>inst</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the size of the memory reference <code>memref</code> in bytes. To handle OP_enter, requires the containing instruction <code>inst</code> to be passed in. For single-instruction string loops, returns the size referenced by each iteration. </p>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
